home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / libraries / mui20dev.lha / MUI / Developer / Autodocs / MUImaster.doc < prev   
Text File  |  1994-02-11  |  18KB  |  590 lines
  1. TABLE OF CONTENTS
  2.  
  3. muimaster.library/--background--
  4. muimaster.library/MUI_AllocAslRequest
  5. muimaster.library/MUI_AslRequest
  6. muimaster.library/MUI_DisposeObject
  7. muimaster.library/MUI_Error
  8. muimaster.library/MUI_FreeAslRequest
  9. muimaster.library/MUI_FreeClass
  10. muimaster.library/MUI_GetClass
  11. muimaster.library/MUI_NewObjectA
  12. muimaster.library/MUI_Redraw
  13. muimaster.library/MUI_RequestA
  14. muimaster.library/MUI_RejectIDCMP
  15. muimaster.library/MUI_RequestIDCMP
  16. muimaster.library/MUI_SetError
  17. muimaster.library/--background--             muimaster.library/--background--
  18.  
  19.    PURPOSE
  20.     muimaster.library contains functions for creating and diposing
  21.     objects, for requester handling and for controlling custom
  22.     classes. Additionally, several of the standard MUI classes are
  23.     built into muimaster.library. For you as a programmer, there
  24.     is no difference between using a builtin class or an external
  25.     class coming as "sys:classes/<foobar>.mui". The MUI object
  26.     generation call takes care of this situation and loads
  27.     external classes automatically when they are needed.
  28.  
  29.  
  30. muimaster.library/MUI_AllocAslRequest   muimaster.library/MUI_AllocAslRequest
  31.  
  32.    NAME
  33.     MUI_AllocAslRequest
  34.  
  35.    FUNCTION
  36.     Provide an interface to asl.library. Using this ensures
  37.     your application will benefit from future expansions
  38.         to MUI's window and iconification handling.
  39.  
  40.    SEE ALSO
  41.     asl.library/AllocAslRequest
  42.  
  43. muimaster.library/MUI_AslRequest
  44.  
  45.    NAME
  46.     MUI_AslRequest
  47.  
  48.    FUNCTION
  49.     Provide an interface to asl.library. Using this ensures
  50.     your application will benefit from future expansions
  51.         to MUI's window and iconification handling.
  52.  
  53.    SEE ALSO
  54.     asl.library/AslRequest
  55.  
  56.  
  57. muimaster.library/MUI_DisposeObject       muimaster.library/MUI_DisposeObject
  58.  
  59.    NAME
  60.     MUI_DisposeObject -- Delete a MUI object.
  61.  
  62.    SYNOPSIS
  63.     MUI_DisposeObject( object )
  64.                        A0
  65.  
  66.     VOID MUI_DisposeObject( APTR );
  67.  
  68.    FUNCTION
  69.     Deletes a MUI object and all of it's auxiliary data.
  70.     These objects are all created by MUI_NewObject(). Objects
  71.     of certain classes "own" other objects, which will also
  72.     be deleted when the object is passed to MUI_DisposeObject().
  73.     Read the per-class documentation carefully to be aware
  74.     of these instances.
  75.  
  76.    INPUTS
  77.     object = abstract pointer to a MUI object returned by
  78.              MUI_NewObject(). The pointer may be NULL, in which case
  79.              this function has no effect.
  80.  
  81.    RESULT
  82.     None.
  83.  
  84.    BUGS
  85.  
  86.    SEE ALSO
  87.     MUI_NewObject(), SetAttrs(), GetAttr().
  88.  
  89.  
  90. muimaster.library/MUI_Error                       muimaster.library/MUI_Error
  91.  
  92.    NAME
  93.     MUI_Error -- Return extra information from the MUI system.
  94.  
  95.    SYNOPSIS
  96.     LONG MUI_Error(VOID);
  97.  
  98.    FUNCTION
  99.     Some MUI functions will set an error if they fail for
  100.     some reason. The error functions is task sensitive,
  101.     only the task that caused the error will receive it
  102.     from this function.
  103.  
  104.    RESULT
  105.     Currently, the following error values are defined:
  106.  
  107.     MUIE_OK                  - no error, everything allright.
  108.     MUIE_OutOfMemory         - went out of memory.
  109.     MUIE_OutOfGfxMemory      - went out of graphics memory.
  110.     MUIE_InvalidWindowObject - NULL window specified.
  111.     MUIE_MissingLibrary      - can't open a needed library.
  112.     MUIE_NoARexx             - unable to create arexx port.
  113.     MUIE_SingleTask          - application is already running.
  114.  
  115.    SEE ALSO
  116.     MUI_SetError()
  117.  
  118.  
  119. muimaster.library/MUI_FreeAslRequest     muimaster.library/MUI_FreeAslRequest
  120.  
  121.    NAME
  122.     MUI_FreeAslRequest
  123.  
  124.    FUNCTION
  125.     Provide an interface to asl.library. Using this ensures
  126.     your application will benefit from future expansions
  127.         to MUI's window and iconification handling.
  128.  
  129.    SEE ALSO
  130.     asl.library/FreeAslRequest
  131.  
  132.  
  133. muimaster.library/MUI_FreeClass               muimaster.library/MUI_FreeClass
  134.  
  135.    NAME
  136.      MUI_FreeClass -- Free class.
  137.  
  138.    SYNOPSIS
  139.     MUI_FreeClass( classptr )
  140.                    A0
  141.  
  142.     VOID MUI_FreeClass(struct IClass *classptr);
  143.  
  144.    FUNCTION
  145.     Free a class pointer obtained with MUI_GetClass(). You may not
  146.     free a class as long as its superclass of some of your custom
  147.     classes. You may not terminate your program without explicitly
  148.     freeing everything obtained with MUI_FreeClass().
  149.  
  150.    INPUTS
  151.     classptr - pointer obtained with MUI_GetClass().
  152.  
  153.    SEE ALSO
  154.     MUI_GetClass()
  155.  
  156.  
  157. muimaster.library/MUI_GetClass                 muimaster.library/MUI_GetClass
  158.  
  159.    NAME
  160.      MUI_GetClass -- Get a pointer to a MUI class.
  161.  
  162.    SYNOPSIS
  163.     class = MUI_GetClass( classid )
  164.     D0                    A0
  165.  
  166.     struct IClass * MUI_GetClass(char *classid);
  167.  
  168.    FUNCTION
  169.     Get a pointer to a MUI class and prevent the clas from
  170.     being expunged.
  171.  
  172.     When you create a custom class with intuition.library/MakeClass(),
  173.     you need to specify the direct superclass of your class. Since
  174.     MUI classes are no public boopsi classes, you will need a pointer
  175.     to the IClass structure here. MUI_GetClass() takes a MUI class
  176.     id (e.g. MUIC_Area, MUIC_Text, ...) and returns the associated
  177.     class pointer. When the class is external, its loaded.
  178.  
  179.     MUI_GetClass() also prevents the specified class from being
  180.     expunged. Once you're done with your custom class, you must
  181.     call MUI_FreeClass() to remove the lock.
  182.  
  183.    INPUTS
  184.     classid - a string describing the MUI class, e.g.
  185.               MUIC_Area, MUIC_Group, ...
  186.  
  187.    RESULT
  188.     class - Pointer to the IClass structure of the specified class.
  189.             You are neither allowed to alter any of its fields nor
  190.             to make any assumptions about its contents. The only
  191.             valid use for this pointer is as parameter for
  192.             intuition.library/MakeClass().
  193.  
  194.             class will be NULL in case of failure.
  195.  
  196.    EXAMPLE
  197.     /* Get a pointer to the superclass. MUI will lock this */
  198.     /* and prevent it from being flushed during you hold   */
  199.     /* the pointer. When you're done, you have to call     */
  200.     /* MUI_FreeClass() to release this lock.               */
  201.  
  202.     if (!(SuperClass=MUI_GetClass(MUIC_Area)))
  203.        fail("Superclass for the new class not found.");
  204.  
  205.     /* Create the new class with the boopsi function call. */
  206.     /* You will need the sizeof your classes instance data */
  207.     /* here.                                               */
  208.  
  209.     if (!(MyClass=MakeClass(NULL,NULL,SuperClass,sizeof(struct Data),0)))
  210.     @{
  211.        MUI_FreeClass(SuperClass);
  212.        fail("Failed to create class.");
  213.     @}
  214.  
  215.     /* Set the dispatcher for the new class. */
  216.  
  217.     MyClass->cl_Dispatcher.h_Entry    = (APTR)MyDispatcher;
  218.     MyClass->cl_Dispatcher.h_SubEntry = NULL;
  219.     MyClass->cl_Dispatcher.h_Data     = NULL;
  220.  
  221.     ...
  222.     ...
  223.  
  224.     app = ApplicationObject,
  225.        ...,
  226.  
  227.        SubWindow, window = WindowObject,
  228.           ...
  229.           WindowContents, VGroup,
  230.  
  231.              Child, MyObj = NewObject(MyClass,NULL,
  232.                 TextFrame,
  233.                 MUIA_Background, MUII_BACKGROUND,
  234.                 TAG_DONE),
  235.  
  236.              End,
  237.  
  238.           End,
  239.        End;
  240.  
  241.     ...
  242.     ...
  243.  
  244.     /* Shutdown. When the application is disposed,
  245.     /* MUI also deletes MyObj. */
  246.  
  247.     MUI_DisposeObject(app);     // dispose all objects.
  248.     FreeClass(MyClass);         // free our private class.
  249.     MUI_FreeClass(SuperClass);  // release super class pointer.
  250.  
  251.    SEE ALSO
  252.     MUI_FreeClass(), intuition.library/MakeClass()
  253.  
  254.  
  255. muimaster.library/MUI_NewObjectA             muimaster.library/MUI_NewObjectA
  256.  
  257.    NAME
  258.     MUI_NewObjectA -- Create an object from a class.
  259.     MUI_NewObject -- Varargs stub for MUI_NewObjectA().
  260.  
  261.    SYNOPSIS
  262.     object = MUI_NewObjectA( class, tags )
  263.     D0                       A0     A1
  264.  
  265.     APTR MUI_NewObjectA( char *, struct TagItem * );
  266.  
  267.     object = MUI_NewObject( classID, Tag1, ... )
  268.  
  269.     APTR MUI_NewObject( classID, ULONG, ... );
  270.  
  271.    FUNCTION
  272.     This is the general method of creating objects from MUI classes.
  273.     You specify a class by its ID string. If the class is not
  274.     already in memory or built into muimaster.library, it will be
  275.     loaded using OpenLibrary("mui/%s",0).
  276.  
  277.     You further specify initial "create-time" attributes for the
  278.     object via a TagItem list, and they are applied to the resulting
  279.     generic data object that is returned. The attributes, their meanings,
  280.     attributes applied only at create-time, and required attributes
  281.     are all defined and documented on a class-by-class basis.
  282.  
  283.    INPUTS
  284.     classID = the name/ID string of a MUI class, e.g. "Image.mui".
  285.               Class names are case sensitive!
  286.  
  287.     tagList = pointer to array of TagItems containing attribute/value
  288.               pairs to be applied to the object being created.
  289.  
  290.    RESULT
  291.     A MUI object, which may be used in different contexts such
  292.     as an application, window or gadget, and may be manipulated
  293.     by generic functions. You eventually free the object using
  294.     MUI_DisposeObject().
  295.     NULL indicates failure, more information on the error can be
  296.     obtained with MUI_Error().
  297.  
  298.    BUGS
  299.  
  300.    SEE ALSO
  301.     MUI_DisposeObject(), MUI_Error(), SetAttrs(), GetAttr().
  302.  
  303.  
  304. muimaster.library/MUI_Redraw                     muimaster.library/MUI_Redraw
  305.  
  306.    NAME
  307.     MUI_Redraw -- Redraw yourself.
  308.  
  309.    SYNOPSIS
  310.     MUI_Redraw( obj, flag )
  311.                 A0   D0
  312.  
  313.     VOID MUI_Redraw( Object *obj, ULONG flag );
  314.  
  315.    FUNCTION
  316.     With MUI_Redraw(), an object tells itself to refresh, e.g. when
  317.     some internal attributes were changed. Calling MUI_Redraw() is
  318.     only legal within a custom class dispatcher, using this function
  319.     within an applications main part is invalid!
  320.  
  321.     Most objects graphical representation in a window depends on some
  322.     attributes. A fuel gauge for example would depend on its
  323.     MUIA_Gauge_Current attribute, an animation object would
  324.     depend on MUIA_Animation_CurrentFrame.
  325.  
  326.     Whenever someone changes such an attribute with a SetAttrs() call,
  327.     the corresponding object receives an OM_SET method with the new
  328.     value. Usually, it could just render itself with some
  329.     graphics.library calls. However, if the object is placed
  330.     in a virtual group or if some other clipping or coordinate
  331.     translation is required, this simple rendering will lead
  332.     into problems.
  333.  
  334.     That's why MUI offers the MUI_Redraw() function call. Instead
  335.     of drawing directly during OM_SET, you should simply call
  336.     MUI_Redraw(). MUI calculates all necessary coordinates
  337.     and clip regions (in case of virtual groups) and then sends
  338.     a MUIM_Draw method to your object.
  339.  
  340.     To emphasize this point again: The only time your object is
  341.     allowed to render something is when you receive a MUIM_Draw
  342.     method. Drawing during other methods is illegal.
  343.  
  344.     Note: As long as no special cases (e.g. virtual groups) are
  345.           present, MUI_Redraw is very quick and calls your MUIM_Draw
  346.           method immediately. No coordinate translations or clip
  347.           regions need to be calculated.
  348.  
  349.    INPUTS
  350.     obj  - pointer to yourself.
  351.     flag - MADF_DRAWOBJECT or MADF_DRAWUPDATE.
  352.            The flag given here affects the objects flags when
  353.            MUI calls the MUIM_Draw method. There are several
  354.            caveats when implementing MUIM_DRAW, see the
  355.            developer documentation for details.
  356.  
  357.    EXAMPLE
  358.  
  359.     LONG mSet(struct IClass *cl,Object *obj,sruct opSet *msg)
  360.     {
  361.        struct Data *data = INST_DATA(cl,obj);
  362.        struct TagItem *tags,*tag;
  363.  
  364.        for (tags=msg->ops_AttrList;tag=NextTagItem(&tags);)
  365.        {
  366.           switch (tag->ti_Tag)
  367.           {
  368.              case MYATTR_PEN_1:
  369.                 data->pen1 = tag->ti_Data;       /* set the new value  */
  370.                 data->mark = 1;                  /* set internal marker*/
  371.                 MUI_Redraw(obj,MADF_DRAWUPDATE); /* update ourselves   */
  372.                 break;
  373.  
  374.              case MYATTR_PEN_1:
  375.                 data->pen2 = tag->ti_Data;       /* set the new value  */
  376.                 data->mark = 2;                  /* set internal marker*/
  377.                 MUI_Redraw(obj,MADF_DRAWUPDATE); /* update ourselves   */
  378.                 break;
  379.           }
  380.        }
  381.  
  382.        return(DoSuperMethodA(cl,obj,msg));
  383.     }
  384.  
  385.     LONG mDraw(struct IClass *cl,Object *obj,struct MUIP_Draw *msg)
  386.     {
  387.        struct Data *data = INST_DATA(cl,obj);
  388.  
  389.        if (msg->flags & MADF_DRAWUPDATE)
  390.        {
  391.           /* called as a result of our MUI_Redraw() during
  392.              MUIM_Set method. Depending on our internal
  393.              marker, we render different things. */
  394.  
  395.           switch (data->mark)
  396.           {
  397.              case 1: RenderChangesFromPen1(cl,obj); break;
  398.              case 2: RenderChangesFromPen2(cl,obj); break;
  399.           }
  400.  
  401.           /* do not call the superclass for speed reasons here.
  402.              it wouldn't do anything anyway since MADF_DRAWUPDATE
  403.              is reserved for custom class use. */
  404.  
  405.           return;
  406.        }
  407.  
  408.        DoSuperMethodA(cl,obj,msg); // let superclass draw frames/etc.
  409.  
  410.        if (msg->flags & MADF_DRAWOBJECT)
  411.        {
  412.           /* complete redraw, maybe the window was just opened. */
  413.           DrawObjectCompletely(cl,obj);
  414.        }
  415.  
  416.        /* if MADF_DRAWOBJECT wasn't set, MUI just wanted to update
  417.           the frame or some other part of our object. In this case
  418.           we just do nothing. */
  419.  
  420.         return(0);
  421.     }
  422.  
  423.    SEE ALSO
  424.     area.mui/MUIM_Draw
  425.  
  426.  
  427. muimaster.library/MUI_RequestA                 muimaster.library/MUI_RequestA
  428.  
  429.    NAME
  430.     MUI_RequestA  -- Pop up a MUI requester.
  431.  
  432.    SYNOPSIS
  433.     MUI_RequestA(app,win,flags,title,gadgets,format,params)
  434.                  D0   D1  D2    A0     A1      A2     A3
  435.  
  436.     LONG MUI_RequestA ( APTR app, APTR win, LONGBITS flags,
  437.          char *title, char *gadgets, char *format, APTR params );
  438.  
  439.     LONG MUI_Request ( APTR app, APTR win, LONGBITS flags,
  440.          char *title, char *gadgets, char *format, ...);
  441.  
  442.    FUNCTION
  443.     Pop up a MUI requester. Using a MUI requester instead
  444.     of a standard system requester offers you the possibility
  445.     to include text containing all the text engine format codes.
  446.  
  447.    INPUTS
  448.     app     - The application object. If you leave this
  449.               NULL, MUI_RequestA() will fall back to a
  450.               standard system requester.
  451.  
  452.     win     - Pointer to a window of the application. If
  453.               this is used, the requester will appear centered
  454.               relative to this window.
  455.  
  456.     flags   - For future expansion, must be 0 for now.
  457.  
  458.     title   - Title for the requester window. Defaults to the
  459.               name of the application when NULL (and app!=NULL).
  460.  
  461.     gadgets - Pointer to a string containing the possible answers.
  462.               The format looks like "_Save|_Use|_Test|_Cancel".
  463.               If you precede an entry with a '*', this answer will
  464.               become the active object. Pressing <Return> will
  465.               terminate the requester with this response. A '_'
  466.               character indicates the keyboard shortcut for this
  467.               response.
  468.  
  469.     format  - A printf-style formatting string.
  470.  
  471.     params  - Pointer to an array of ULONG containing the parameter
  472.               values for format.
  473.  
  474.    RESULT
  475.     0, 1, ..., N = Successive id values, for the gadgets
  476.     you specify for the requester.  NOTE: The numbering
  477.     from left to right is actually: 1, 2, ..., N, 0.
  478.  
  479.    SEE ALSO
  480.     MUIA_Text_Contents
  481.  
  482.  
  483. muimaster.library/MUI_RejectIDCMP           muimaster.library/MUI_RejectIDCMP
  484.  
  485.    NAME
  486.      MUI_RejectIDCMP -- Reject previously requested input events.
  487.  
  488.    SYNOPSIS
  489.     MUI_RejectIDCMP( obj, flags )
  490.                       A0   D0
  491.  
  492.     VOID MUI_RejectIDCMP( Object *obj, ULONG flags );
  493.  
  494.    FUNCTION
  495.     Reject previously requested input events. You should
  496.     ensure that you reject all input events you requested
  497.     for an object before it gets disposed. Rejecting
  498.     flags that you never requested has no effect.
  499.  
  500.     Critical flags such as IDCMP_MOUSEMOVE and IDCMP_INTUITICKS
  501.     should be rejected as soon as possible. See MUI_RequestIDCMP()
  502.     for details.
  503.  
  504.    INPUTS
  505.     obj   - pointer to yourself as an object.
  506.     flags - one or more IDCMP_XXXX flags.
  507.  
  508.    EXAMPLE
  509.     LONG CleanupMethod(struct IClass *cl, Object *obj, Msg msg)
  510.     {
  511.        MUI_RejectIDCMP( obj, IDCMP_MOUSEBUTTONS|IDCMP_RAWKEY );
  512.        return(DoSuperMethodA(cl,obj,msg));
  513.     }
  514.  
  515.    SEE ALSO
  516.     MUI_RequestIDMCP()
  517.  
  518.  
  519. muimaster.library/MUI_RequestIDCMP         muimaster.library/MUI_RequestIDCMP
  520.  
  521.    NAME
  522.      MUI_RequestIDCMP -- Request input events for your custom class.
  523.  
  524.    SYNOPSIS
  525.     MUI_RequestIDCMP( obj, flags )
  526.                       A0   D0
  527.  
  528.     VOID MUI_RequestIDCMP( Object *obj, ULONG flags );
  529.  
  530.    FUNCTION
  531.     If your custom class needs to do some input handling, you must
  532.     explicitly request the events you want to receive. You can
  533.     request (and reject) events at any time.
  534.  
  535.     Whenever an input event you requested arrives at your parent
  536.     windows message port, your object will receive a
  537.     MUIM_HandleInput method.
  538.  
  539.     Note: Time consuming IDCMP flags such as IDCMP_INTUITICKS and
  540.           IDCMP_MOUSEMOVE should be handled with care. Too many
  541.           objects receiving them will degrade performance With
  542.           the following paragraph in mind, this isn't really
  543.           a problem:
  544.  
  545.           You should try to request critical events only when you
  546.           really need them and reject them with MUI_RejectIDCMP()
  547.           as soon as possible. Usually, mouse controlled objects
  548.           only need MOUSEMOVES and INTUITICKS when a button
  549.           is pressed. You should request these flags only
  550.           on demand, i.e. after receiving a mouse down event
  551.           and reject them immediately after the button has been
  552.           released.
  553.  
  554.    INPUTS
  555.     obj   - pointer to yourself as an object.
  556.     flags - one or more IDCMP_XXXX flags.
  557.  
  558.    EXAMPLE
  559.     LONG SetupMethod(struct IClass *cl, Object *obj, Msg msg)
  560.     {
  561.        if (!DoSuperMethodA(cl,obj,msg))
  562.           return(FALSE);
  563.  
  564.        /* do some setup here... */
  565.        ...;
  566.  
  567.        /* i need mousebutton events and keyboard */
  568.        MUI_RequestIDCMP( obj, IDCMP_MOUSEBUTTONS|IDCMP_RAWKEY );
  569.  
  570.        return(TRUE);
  571.     }
  572.  
  573.    SEE ALSO
  574.     MUI_RejectIDMCP()
  575.  
  576. muimaster.library/MUI_SetError                 muimaster.library/MUI_SetError
  577.  
  578.    NAME
  579.      MUI_SetError -- Set an error value.
  580.  
  581.    SYNOPSIS
  582.     VOID MUI_SetError(LONG);
  583.  
  584.    FUNCTION
  585.     Setup a MUI error. MUI_Error() will return this value when
  586.     asked.
  587.  
  588.    SEE ALSO
  589.     MUI_Error()
  590.